home *** CD-ROM | disk | FTP | other *** search
/ Ham Radio 2000 #2 / Ham Radio 2000 - Volume 2.iso / HAMV2 / TCP_IP / TNOS230S / SAMAPI.H < prev    next >
Encoding:
C/C++ Source or Header  |  1996-05-05  |  12.6 KB  |  293 lines
  1. /*
  2.  * samapi.h
  3.  *
  4.  * Structures, command codes, etc that define the application program
  5.  * interface to SAM Amateur Radio Callsign Database.
  6.  *
  7.  * Copyright 1991 by Tom Thompson, Athens, AL and by RT Systems
  8.  *                   [n4yos]
  9.  *
  10.  * SAMAPI.EXE implements this API.  When run, it stays resident and
  11.  * is called via int 2f, ah = dynamically assigned id.
  12.  * This is commonly called the "multiplex interrupt" interface.
  13.  * Per convention, int 2fh, ah = muxid, al = 0 is an install check, and
  14.  * al comes back non-zero if the API is installed.  For other API
  15.  * functions:
  16.  *
  17.  *      ah = muxid
  18.  *      al = 1
  19.  *   ds:si = pointer to command block
  20.  *   es:di = pointer to result block
  21.  *
  22.  * No registers are changed by SAMAPI (except al when input al == 0)
  23.  *
  24.  *
  25.  * The command block always starts with a header (chdr_t).  The
  26.  * header contains a command code to select a particular API
  27.  * function.  The header is followed by additional parameters as
  28.  * needed for the selected function.
  29.  *
  30.  * The response, or result block, also starts with a header (rhdr_t).
  31.  * This contains an error code (which is 0 for no error).  Following
  32.  * the header are additional results depending on the API function.
  33.  *
  34.  * The main item of interest returned by the API functions is the
  35.  * data record for a given ham.  See datarec_t below for the layout
  36.  * of the data record.
  37.  *
  38.  * The data record can be in various stages of "unpackedness".  Many
  39.  * of the string fields in the data base are implemented by pointers
  40.  * in the main data record to compressed dictionaries.  Since unpacking
  41.  * these fields is time consuming, each API record retrieval function
  42.  * allows you to specify what fields will/won't be unpacked.  There
  43.  * is also a function to get the dictionary code (or pointer) for
  44.  * a particular string.  All these features can be combined to
  45.  * implement fast sequential searches without having to unpack each
  46.  * record.
  47.  *
  48.  * the field PackFlags in the datarecord describes which fields
  49.  * are unpacked.  A bit is clear (0) to indicate a corresponding
  50.  * field is unpacked.
  51.  *   Bit  Field
  52.  *  ----  -----
  53.  *    0    LastName
  54.  *    1    FirstName
  55.  *    2    Address
  56.  *    3    City
  57.  *    4    State
  58.  *    5    Zip
  59.  *    6    Date of Birth
  60.  *
  61.  * (Note, Zip and Dob are not in dictionaries, but avoiding converting
  62.  *  them to strings saves time over long searches)
  63.  *
  64.  * When you are faced with a packed record and you want it unpacked, the
  65.  * method is to issue API command SamGetRecordByCall with index = Cindex.
  66.  *
  67.  * There are API commands to find records by callsign, by name,
  68.  * by record number (in callsign order), and by name record number.
  69.  *
  70.  * There is also a command to find a county from a zip code string.  The
  71.  * optional file SAMDBZ.DAT must be present.
  72.  *
  73.  * Cindex is the absolute record number.
  74.  * Nindex indexes an index of the database sorted by name.
  75.  *
  76.  * Given no bugs (ha!), the normal error return for the find functions
  77.  * (and dictionary code get) is SerrNotFound.  The normal error return
  78.  * for the set version business is SerrFail.
  79.  *
  80.  * Whenever a find record function fails, a record is always returned.
  81.  * This is the closest lower record whenever a match cannot be made.
  82.  * In the case of an illegal index, its usually record #0 that is
  83.  * returned.  So if you don't get an exact match, you can start
  84.  * browsing starting at the returned record.
  85.  *
  86.  * The get dict code function DOES NOT return anything useful unless
  87.  * there is an exact match.
  88.  */
  89.  
  90. #define DEFAULT_SAMMUX 0x99    /* default mux id (ah on int 0x2f to access API) */
  91.  
  92. typedef struct datarecord
  93. {
  94.     long Cindex;            /* sorted by call index */
  95.     long Nindex;            /* sorted by name index */
  96.     long LastNameCode;      /* last name dictionary code */
  97.     long FirstNameCode;     /* first name dict. code */
  98.     long AddressCode;       /* address dict. code */
  99.     long CityCode;          /* city dict. code */
  100.     long StateCode;         /* state dict. code (note this one 16 bits) */
  101.     long ZipNumber;         /* zip code number 0-99999 (SEE CANADA NOTE) */
  102.     short DobNumber;        /* date of birth number 0-99*/
  103.     short PackFlags;        /* bitmask of fields that are not unpacked */
  104.     char Call[6+1];         /* call, area is always Call[2] */
  105.     char Class[1+1];        /* class, N,T,G,A, or E */
  106.     char LastName[20+1];    /* last name, 20 max */
  107.     char FirstName[11+1];   /* first name, 11 max */
  108.     char MidInitial[1+1];   /* middle initial */
  109.     char Address[35+1];     /* mailing address, 35 max */
  110.     char City[20+1];        /* city, 20 max */
  111.     char State[2+1];        /* state */
  112.     char Zip[5+1];          /* zip code string (SEE CANADA NOTE) */
  113.     char Dob[2+1];          /* date of birth string "00" to "99" */
  114.     char reserved[11];
  115. } datarec_t;
  116.  
  117. /*
  118.  * CANADA NOTE
  119.  *
  120.  * When a datarec_t contains a canadian call:
  121.  *
  122.  * The .Zip field contains 6 characters for the postal code.  The
  123.  * terminating zero is in the first byte of the .Dob field (therefore
  124.  * .Dob is a 0-length string).
  125.  *
  126.  * .ZipNumber is the postal code packed as follows:
  127.  *
  128.  * Bit # |31  27 |26  22 |21 18 |17  13 |12  9 | 8   4 | 3  0 |
  129.  *       | 00000 | xxxxx | xxxx | xxxxx | xxxx | xxxxx | xxxx |
  130.  *       |       |  c0   |  c1  |  c2   |  c3  |  c4   |  c5  |
  131.  *
  132.  * Add 'A' to c0, c2, and c4 to obtain alpha character
  133.  * Add '0' to c1, c3, and c5 to obtain numeric character
  134.  *
  135.  * Examples: PostalCode  Binary--------------------------------
  136.  *           A0A 0A0     00000 00000 0000 00000 0000 00000 0000
  137.  *           Z9Z 9Z9     00000 11111 1111 11111 1111 11111 1111
  138.  *           B7C 8D9     00000 00001 0111 00010 1000 00011 1001
  139.  */
  140.  
  141. /* API command buffer (DS:SI) header */
  142.  
  143. typedef struct cmd_header
  144. {
  145.     unsigned char cmd;
  146.     unsigned char fill[2];
  147.     unsigned char country;    /* 0: USA, 1:Canada */
  148. } chdr_t;
  149.  
  150. /* API response buffer (ES:DI) header */
  151.  
  152. typedef struct rsp_header
  153. {
  154.     unsigned char err;
  155.     unsigned char xerr;
  156.     unsigned char fill[2];
  157. } rhdr_t;
  158.  
  159. /* API commands */
  160.                                 /*--------------------------------------*/
  161. #define SamGetVersion       0
  162.     /* in: */                   /* chdr_t */
  163.     /* out: */                  typedef struct {
  164.                                     rhdr_t h; short version; short level;
  165.                                 } rspversion_t;
  166.                                 /*--------------------------------------*/
  167.                                 /* if you find a later version/level    */
  168.                                 /* than you programmed for, you can chk */
  169.                                 /* compat. by attempting to set level   */
  170. #define SamSetLevel         1
  171.     /* in: */                   typedef struct {
  172.                                     chdr_t h; short level;
  173.                                 } cmdsetlevel_t;
  174.     /* out: */                  /* rhdr_t */
  175.                                 /*--------------------------------------*/
  176.                                 /* over 500k at last count and growing! */
  177. #define SamGetNumRecs       2
  178.     /* in: */                   /* chdr_t */
  179.     /* out: */                  typedef struct {
  180.                                     rhdr_t h; long numrecs;
  181.                                 } rspnumrecs_t;
  182.                                 /*--------------------------------------*/
  183.                                 /* date of data. scope is               */
  184.                                 /* something like "All USA Calls" or    */
  185.                                 /* "District 4" or "New York"           */
  186. #define SamGetDatabaseDate  3
  187.     /* in: */                   /* chdr_t */
  188.     /* out: */                  typedef struct {
  189.                                     rhdr_t h;
  190.                                     char date[9+1]; char scope[24+1];
  191.                                 } rspdbdate_t;
  192.                                 /*--------------------------------------*/
  193.                                 /* find record containing matching call */
  194.                                 /* (packflags = 0 for all unpacked)     */
  195. #define SamFindCall         4
  196.     /* in: */                   typedef struct {
  197.                                     chdr_t h;
  198.                                     short packflags;
  199.                                     char call[6+1];
  200.                                 } cmdfindcall_t;
  201.     /* out: */                  typedef struct {
  202.                                     rhdr_t h; datarec_t d;
  203.                                 } rspdatarec_t;
  204.                                 /*--------------------------------------*/
  205.                                 /* get record with matching Cindex      */
  206. #define SamGetRecordByCall  5
  207.     /* in: */                   typedef struct {
  208.                                     chdr_t h;
  209.                                     short packflags;
  210.                                     long index;    /* Cindex (or Nindex) */
  211.                                 } cmdgetrecs_t;
  212.     /* out: */                  /* rspdatarec_t */
  213.                                 /*--------------------------------------*/
  214.                                 /* find record with matching (or close) */
  215.                                 /* name                                 */
  216. #define SamFindName         6
  217.     /* in: */                   typedef struct {
  218.                                     chdr_t h;
  219.                                     short packflags;
  220.                                     char lastname[20+1];
  221.                                     char firstname[11+1];
  222.                                     char midinitial[1+1];
  223.                                 } cmdfindname_t;
  224.     /* out: */                  /* rspdatarec_t */
  225.                                 /*--------------------------------------*/
  226.                                 /* find record with matching Nindex     */
  227.                                 /* NOTE: SamFindCall and                */
  228.                                 /* SamGetRecordbyCall return with       */
  229.                                 /* Nindex == -1                         */
  230. #define SamGetRecordByName  7
  231.     /* in: */                   /* cmdgetrecs_t */
  232.     /* out: */                  /* rspdatarec_t */
  233.                                 /*--------------------------------------*/
  234.                                 /* Use this to implement fast sequential*/
  235.                                 /* searches.  Look thru records without */
  236.                                 /* unpacking them                       */
  237. #define SamGetDictCode      8
  238.     /* in: */                   typedef struct {
  239.                                     chdr_t h;
  240.                                     short dno;    /* dictionary number */
  241.                                     char string[35+1];
  242.                                 } cmdgetdictcode_t;
  243.     /* out: */                  typedef struct {
  244.                                     rhdr_t h; long dictcode;
  245.                                 } rspgetdictcode_t;
  246.                                 /*--------------------------------------*/
  247.                                 /* preps SAMAPI.EXE for removal (best   */
  248.                                 /* not used, do it with SAMAPI /r)      */
  249. #define SamRemove          20
  250.     /* in: */                   /* chdr_t */
  251.     /* out: */                  /* rhdr_t */
  252.                                 /*--------------------------------------*/
  253.                                 /* lookup county name from zip code     */
  254. #define SamFindCounty      21
  255.     /* in: */                   typedef struct {
  256.                                     chdr_t h;
  257.                                     char zip[5+1];
  258.                                     char reserved[2];
  259.                                 } cmdfindcounty_t;
  260.     /* out: */                  typedef struct {
  261.                                     rhdr_t h;
  262.                                     char county[31+1];
  263.                                 } rspfindcounty_t;
  264.  
  265.  
  266.  
  267. /* API error returns */
  268. #define SerrNoError         0
  269. #define SerrNotFound        1    /* normal error */
  270. #define SerrFail            2    /* normal error for setlevel */
  271. #define SerrBadCmd          3    /* bad input from API caller */
  272. #define SerrFatal           4    /* SAMAPI internal error */
  273. #define SerrCountry            6    /* invalid country */
  274.  
  275.  
  276. /* Dictionary Numbers */
  277. #define DnoLastName         0
  278. #define DnoFirstName        1
  279. #define DnoAddress          2
  280. #define DnoCity             3
  281. #define DnoState            4
  282.  
  283. /* Pack bits */
  284. #define PB_LASTNAME  1
  285. #define PB_FIRSTNAME 2
  286. #define PB_ADDRESS   4
  287. #define PB_CITY      8
  288. #define PB_STATE    16
  289. #define PB_ZIP      32
  290. #define PB_DOB      64
  291. #define PB_ALL      (0x7f)
  292.  
  293.